home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / gfxcard / chunkyppc / chunkyppc.docs < prev    next >
Text File  |  1999-11-29  |  14KB  |  415 lines
  1. The ChunkyPPC Library
  2. =====================
  3.  
  4. --- snip ---
  5.  
  6. Newsflash:
  7.  
  8. This is a major new version of chunkyppc.library.
  9.  
  10. Note: The new functions are ONLY supported if you use chunkyppc.library
  11. as library, using it with linkchunkyppc.lib does not support the new
  12. functions !!! I included the old version of the linkchunkyppc.lib though,
  13. it just does not cover the new functions of V3+. If you need V3+, use
  14. it as Shared Library.
  15.  
  16. Mainly i included some new functions on request from *Hyperion Software* !!!
  17.  
  18. Hyperion wanted a OpenScreen/CloseScreen interface which can handle:
  19.  
  20. - Open on a Screen
  21. - Open on a WB Window
  22. - Open on a PIP Window
  23. - Open on a Pubscreen
  24. - use ASL Requester, not rtgmaster
  25. - rtgmaster requester optionally
  26. - change screenmodes of a running program "on the fly" (without having
  27.   to quit the program)
  28. - automatically handle Chunky-Format Conversions
  29. - Support for all 16 Bit Formats, RGB15 and LUT8 needed
  30. - For AGA 8 Bit and HAM8 needed
  31. - LoadRGB32 Feature with included Color-Adaption for WB-Window
  32. - Doublebuffering (both AllocScreenBuffer and ScrollVPort) and
  33.   Triple Buffering Support
  34. - Support for Custom Hooks both on 68k and WarpUP
  35. - has to work on both 68k and PowerPC (WarpUP)
  36.  
  37. Note: AGA Mode claims to be 15 Bit, but is really 16 Bit :) Just always
  38. use PIXFMT_RGB15 for AGA in ChunkyInit :)
  39.  
  40. Note: Executables compiled for chunkyppc.library V3-V11 (which were internal
  41. releases anyways) don't work anymore on V11. This is V14. If you have a
  42. Beta V3-V9, don't give it to anyone, to avoid confusion. Only versions
  43. which should be given to other people are V14 or the old V2 ones. But
  44. nothing "in-between".
  45.  
  46. Note: Due to the special implementation of EGCS-WarpUP the ms.algo cannot
  47. be called directly with it. Use The CallChunkyCopy #define in the
  48. include instead. For other compilers you can just
  49.  
  50. #define CallChunkyCopy ms.algo
  51.  
  52. Since V3.0 chunkyppc.library supports these features.
  53.  
  54. There are the following new functions:
  55.  
  56. OpenGraphics
  57. ------------
  58.  
  59. a0 : Title (of the program)
  60. a1 : Mode_Screen structure
  61. d0 : override flag
  62.  
  63. This function opens a screenmode-requester and after this a screen/window.
  64. It uses the following env-variables:
  65.  
  66. <Title>/modeid:
  67.  
  68. if the override flag is *not* set, use this modeid, if the ENV Variable
  69. is set (and if not, open a screenmode requester). If the flag is set, always
  70. open a screenmode requester. So default a Screenmode can be used, once the
  71. user saved one, but the screenmode can in-game still be changed.
  72.  
  73. Since V5 there is (on request of Hyperion Software) a override mode == 2.
  74. If this is set, inside env:<Title> (and envarc:<Title>) there will be a
  75. small Screenmode Database. OpenGraphics() then checks, if a modeid file
  76. is already found in the directory, if this modeid file has the correct
  77. resolution. This way it is possible to maintain several different resolutions
  78. in one database, without the screenmode-requester popping up on every
  79. screen-width/height/depth change (the names of the files are modeid,
  80. modeid1, modeid2, ...). Up to 21 entries (modeid, modeid1, ..., modeid20)
  81. are supported, if more are entered, modeid20 is changed always).
  82.  
  83. <Title>/dbuf:
  84.  
  85. Use Doublebuffering
  86.  
  87. <Title>/oldstyle
  88.  
  89. If this is set, ScrollVPort will be used, else Triple Buffering using
  90. ScreenBuffers.
  91.  
  92. <Title>/wb
  93.  
  94. If this is set, a Workbench Window will be used, not a screen
  95.  
  96. <Title>/pip
  97.  
  98. If this is set, a Picture in Picture will be used using the Picasso96API.library.
  99. Note: Not all Graphics Boards Support this. Currently only P96 PIP is supported,
  100. not CGX. Maybe in the future...
  101.  
  102. <Title>/ham
  103.  
  104. Use HAM8 mode for AGA. If this is not set, 8 Bit mode is used for AGA.
  105.  
  106. <Title>/pipnoclear
  107.  
  108. If this is set to 1, the PIP won't be cleared when opened.
  109.  
  110. <Title>/rtgmaster
  111.  
  112. Use rtgmaster Screenmode Requester instead of ASL one. rtgmaster.library
  113. will only be opened when this option is set, so that rtgmaster.library
  114. does not need to be installed to be able to use chunkyppc.library.
  115.  
  116. <Title>/likecgx
  117.  
  118. If you want CGX-like WB Window Support for P96 (Faster, but Window Borders
  119. disappear). For CGX it is automatically set, as it is the only possible
  120. method for CGX to reach (at least for 16 Bit) WB Window Support, for P96
  121. it is optional.
  122.  
  123. Hyperion Software will support a GUI to set these ENV-Variables for their
  124. products, as they told me.
  125.  
  126. The Mode_Screen structure is a special structure containing information
  127. on the screen, like the Screen-Structure of Intuition or the RtgScreen
  128. structure of rtgmaster. It does not matter if you got it by OpenGraphics
  129. or constructed it yourselves. The Mode_Screen structure also gets the
  130. minimum/maximum Width/Height/Depth, so you should init these values before you
  131. call OpenGraphics.
  132.  
  133. If the video_screen element of Mode_Screen is !=0 this screen will be closed,
  134. and a new one will be opened ("on-the-fly-screen-change").
  135.  
  136. The important elements of Mode_Screen (like defined in clib/chunkyppc_protos.h):
  137.  
  138. video_screen: An Intuition Screen
  139. video_window: An Intuition Window
  140. bpr: Bytes Per Row
  141. mode: The ModeID
  142. SCREENWIDTH: Minimal Width/Actual Width
  143. SCREENHEIGHT: Minimal Height/Actual Height
  144. MAXWIDTH: Maximum Width
  145. MAXHEIGHT: Maximum Height
  146. MINDEPTH: Minimum Depth
  147. MAXDEPTH: Maximum Depth
  148. format: Video Format (using Cybergraphics constants)
  149. video_depth: BitsPerPixel
  150. screen: Buffer 0 Video RAM / Address BitPlane 0
  151. screenb: Buffer 1 Video RAM / Address Bitplane 1
  152. screenc: Buffer 2 Video RAM / Address Bitplane 2
  153. bufnum: Active Buffer number
  154. bitmapa-bitmapc: the Bitmaps
  155. thebitmap: Active Bitmap
  156. numbuffers: Number of Buffers (ScrollVPort only 2, no DBuffering only 1)
  157. algo: Function-pointer to Chunky-Copy Algorithm
  158.  
  159. CloseGraphics
  160. -------------
  161.  
  162. a0: Mode_Screen structure
  163. d0: shutdownlibs Flag
  164.  
  165. This closes the Screen/Window again (and all other stuff... :) )
  166.  
  167. If shutdownlibs is set, the libraries used will also be closed.
  168. If not they will not be closed.
  169.  
  170. LoadColors
  171. ----------
  172.  
  173. This is basically the same like LoadRGB32 of graphics.library or
  174. LoadRGBRtg of rtgmaster. Set the colors of a 8 Bit Screen. Does nothing
  175. for a 15/16 Bit Screen.
  176.  
  177. a0: Mode_Screen structure
  178. a1: Color-array like for LoadRGB32/LoadRGBRtg
  179.  
  180. DoubleBuffer
  181. ------------
  182.  
  183. a0: Mode_Screen structure
  184.  
  185. Causes Double/Triplebuffering (depending on value of env:<Title>/oldstyle
  186. and env:<Title>/dbuf). Note WB Window and PIP Modes are single buffered.
  187. For Single-Buffered this does not do anything. For Triplebuffering it
  188. switches buffers in the sequence (when the screen is just opened buffer
  189. 0 is always active !!!) <0 is active at startup>-1-2-0-1-2-0 or
  190. <0 is active at startup>-1-0-1-0...
  191.  
  192. ChunkyInit
  193. ----------
  194.  
  195. r4: Mode_Screen structure
  196. r5: srcformat
  197.  
  198. This initializes ms->algo with a PowerPC ChunkyCopy/c2p including Colorformat
  199. Conversion according to src and destination format (ms->format...).
  200.  
  201. ChunkyInit68k
  202. -------------
  203.  
  204. a0: Mode_Screen structure
  205. d0: srcformat
  206.  
  207. This time a 68k function, and initializes ms->algo with a 68k algorithm.
  208.  
  209. If ChunkyInit/ChunkyInit68k returns 0, this means the source and the
  210. destination formats are incompatible !!!
  211.  
  212. The following formats are compatible currently:
  213.  
  214. - for PowerPC all 8 Bit and 16 Bit formats, and RGB15 15 Bit Format
  215. - on 68k 8 Bit and all 15 Bit and 16 Bit formats, but 15/16 Bit only
  216.   if source and destination have identical formats (68k currently
  217.   does not support format conversion)
  218. - For AGA: On Workbench Window only 8 Bit, naturally
  219. - For AGA: HAM8 mode only on PowerPC
  220. - On Workbench Window: 15/16 Bit formats only supported for Picasso 96,
  221.   as WritePixelArray of CyberGraphX does not support a 15/16 Bit
  222.   Input Format. On a Screen it is supported also for CGX though.
  223.   If you want this on CGX too -> write the CGX authors about it.
  224.  
  225. The Chunky Algorithms
  226. ---------------------
  227.  
  228. 68k:
  229.  
  230. a0: Mode_Screen structure
  231. a1: dest
  232. a2: src
  233. d0: srcformat
  234. d1: hook68k
  235. d2: data
  236.  
  237. PPC:
  238.  
  239. r4: Mode_Screen structure
  240. r5: dest
  241. r6: src
  242. r7: srcformat
  243. r8: hook68k
  244. r9: data
  245.  
  246. This performs a fullscreen copy of "src" to "dest" performing all
  247. needed format conversion. srcformat is in CyberGraphics Synax
  248. (PIXFMT_RGB16 or such). src is a Video RAM Pointer for GFX Board (you
  249. have to take care yourselves, if that of buffer 0,1 or 2 has to be
  250. provided). For AGA it is a pointer to the correct Bitmap instead !!!
  251.  
  252. After the Copy has been done, the hook68k will be performed using
  253. a Contextswitch (or for 68k as function call), if hook68k is != 0.
  254. If hook68k is 0 this will not be done. data is the parameter (void *)
  255. of hook68k, and the function returns the return value of the hook
  256. (or 0, if no Hook was provided).
  257.  
  258. Why this ?
  259.  
  260. There are some things which can't be run on the PPC:
  261.  
  262. - lowlevel.library
  263. - Keyboard Code
  264. - Sound Code
  265. - Doublebuffering
  266. - LoadColors
  267.  
  268. Most program authors perform one contextswitch for each of those.
  269. Every contextswitch takes away 0.5-0.6 ms. Now it is possible
  270. to put several of them together to one 68k function, and call this
  271. function right after the Chunky-Copy, to reduce the number of
  272. Contextswitches per loop to *1*. This is optional code, you still
  273. can set the Hook-Parameter to 0.
  274.  
  275. Yes, i said before that Hooks are not possible for PPC. They
  276. are possible, but only with a MixedBinary like chunkyppc.library.
  277. To generate the 68k functions for the Hook you can do:
  278.  
  279. - Create a 68k Shared Library containing the 68k function
  280. - or using a MixedBinary
  281.  
  282. I don't know which one Hyperion will be using. But generally i advice
  283. people to use a library to avoid MixedBinaries.
  284.  
  285. There is an example about the MixedBinary feature consisting of the
  286. two files test_new.c and test_new_68k.c. I fear, though, that it will
  287. only compile with StormC, as it uses the "Automatic Contextswitch"
  288. feature of StormC. You could also create the "myhook" function inside
  289. a Custom 68k Shared library of course.
  290.  
  291. --- snap ---
  292.  
  293. And now follows the documentation about the features of the "old"
  294. version V2 which of course still work :)
  295.  
  296. Well, why another Chunky-Library ? We have rtgmaster, after all...
  297.  
  298. Well, rtgmaster has one BIG BIG function for chunky-copy. Sometimes if
  299. you know a certain special-case exists, you can specifically optimize
  300. for this special-case and get some extra speed out of it. The disadvantage
  301. is of course that you now have TONS of different chunky-copy-functions,
  302. and get confused about which of them is which :)
  303.  
  304. Well, anyways: the chunkyppc.library works with rtgmaster (Just use
  305.  
  306. GetBufAdr(RtgScreen,0)
  307.  
  308. as Screenaddress
  309.  
  310. ), it works with CGX, it works with Picasso96. It works with AGA. It works
  311. with ECS.
  312.  
  313. It also contains all my experience in the field of GFX Board Coding.
  314.  
  315. chunkyppc.library exists in two forms:
  316.  
  317. chunkyppc.library is a PPC Shared Library for WarpUP (for newer versions of
  318. StormC and for vbcc-WarpUP the linker-lib chunkyppc.lib is provided, for
  319. older versions of StormC and for EGCS-WarpUP Includes are provided, which
  320. serve the same thing).
  321.  
  322. linkchunkyppc.lib is a Linker Lib without Shared Library which serves the same
  323. purpose, and supports the same functions. It cannot be used with EGCS WarpUP,
  324. though, as EGCS WarpUP does not support vbcc-WarpUP-Style linkerlibs, like the
  325. other two compilers... for EGCS WarpUP you have to use the PPC Shared Library.
  326.  
  327. The functions:
  328.  
  329. ChunkyNoffFast
  330. ChunkyNoffFastest
  331. ChunkyNoffNormal
  332.  
  333. Chunky-Copy with no destination offset and no source offset. Useful for
  334. Fullscreen-Copy. Fastest assumes the width divisible by 64, Fast divisible
  335. by 8, and Normal does not assume anything. Of course the more limited the faster...
  336.  
  337. ChunkyFast
  338. ChunkyFastest
  339. ChunkyNormal
  340.  
  341. The same like above, only now with Destination Offset Added.
  342.  
  343. ChunkyFastFull
  344. ChunkyFastestFull
  345. ChunkyNormalFull
  346.  
  347. Now both sorts of Offset (Source+Destination) are supported. Note, that because
  348. some compilers - EGCS WarpUP in special - don't like many parameters for PPC
  349. Shared Libs, i stuffed some parameters together into a
  350.  
  351. struct Soff
  352. {
  353.  int x,y;
  354. };
  355.  
  356. for this ... some of the future functions use this too... should be easy to
  357. understand :)
  358.  
  359. All Chunky-Copy functions are 100% highly optimized PPC ASM. I *really* spent
  360. time to optimize them best. Some of the c2p are only C (c2p_1 and c2p_2 are
  361. PPC ASM). I guess c2p_1 is the fastest, then c2p_2, then c2p_3, then c2p_4,
  362. but never really tested it...
  363.  
  364. Names in the fd-file:
  365.  
  366. address = Destination Address
  367. data    = Source Address
  368. w       = Width of the Blit
  369. h       = Height of the Blit
  370. bpr     = Destination BytesPerRow
  371. x       = Destination X Offset
  372. y       = Destination Y Offset
  373. soff    = Source Offset (struct Soff *)
  374. sbpr    = Source BytesPerRow
  375. buffer  = Destination Address
  376. width   = Width of the Blit
  377. height  = Height of the Blit
  378. bm      = struct BitMap * of the Screen
  379. dest    = Destination Offset (struct Soff *)
  380. size    = Width/Height of the Blit (struct Soff *)
  381. plane0  = bm->Planes[0]
  382. bitplanes = bm->Planes[0]
  383. chunkyx  = Width of the Blit
  384. chunkyy  = Height of the Blit
  385. bitplanesize = (width*height)/8
  386. depth    = 6 or 8
  387. helpbfr  = width*height sized FastRAM Buffer
  388. temp     = width*height sized FastRAM Buffer
  389. screensize = Size of the Screen (struct Soff *)
  390.  
  391. In the future there will be 15-24 Bit support, even with Byteswapping,
  392. HAM8 Support and Masking Support.
  393.  
  394. There won't be a 68k Version. It would be too much work for my lazy self
  395. to transform all that PPC ASM Code to 68k :)
  396.  
  397. Note: In the meanwhile there are also functions for:
  398.  
  399. 16 BIT
  400. 16 BIT with Byteswapper
  401. 16 Bit with RGB<->BGR change
  402. 24 Bit
  403. 32 Bit
  404.  
  405. 16 Bit with Swapper AND rotater still has to be done, as quite a lot of
  406. possible 24/32 Bit changers. Also 16-24 Bit are currently only available
  407. in the "normal" versions. ROT(RGB<->BGR) is completely untested.
  408. For 15 Bit the 16 Bit functions can be used.
  409.  
  410. Who does write me docs ? :)
  411.  
  412. Look at the includes for the new functions for 16-24 Bit :)
  413.  
  414. Steffen Haeuser
  415.